<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Introduction - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.acl.introduction.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.acl.introduction.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.acl.html">Zend_Acl</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.acl.html">Zend_Acl</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.acl.refining.html">Refining Access Controls</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.acl.introduction" class="section"><div class="info"><h1 class="title">Introduction</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Acl</span> provides a lightweight and flexible access control list
        (<acronym class="acronym">ACL</acronym>) implementation for privileges management. In general, an
        application may utilize such <acronym class="acronym">ACL</acronym>&#039;s to control access to certain
        protected objects by other requesting objects.
    </p>

    <p class="para">
        For the purposes of this documentation:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                a <em class="emphasis">resource</em> is an object
                to which access is controlled.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                a <em class="emphasis">role</em> is an object
                that may request access to a Resource.
            </p>
        </li>
    </ul>

    <p class="para">
        Put simply, <em class="emphasis">roles request access to resources</em>. For
        example, if a parking attendant requests access to a car, then the parking attendant is the
        requesting role, and the car is the resource, since access to the car may not be granted to
        everyone.
    </p>

    <p class="para">
        Through the specification and use of an <acronym class="acronym">ACL</acronym>, an application may control
        how roles are granted access to resources.
    </p>

    <div class="section" id="zend.acl.introduction.resources"><div class="info"><h1 class="title">Resources</h1></div>
        

        <p class="para">
            Creating a resource in <span class="classname">Zend_Acl</span> is very simple.
            <span class="classname">Zend_Acl</span> provides the resource,
            <span class="classname">Zend_Acl_Resource_Interface</span>, to facilitate creating resources in
            an application. A class need only implement this interface, which consists of a single
            method,  <span class="methodname">getResourceId()</span>, for <span class="classname">Zend_Acl</span> to
            recognize the object as a resource. Additionally,
            <span class="classname">Zend_Acl_Resource</span> is provided by <span class="classname">Zend_Acl</span>
            as a basic resource implementation for developers to extend as needed.
        </p>

        <p class="para">
            <span class="classname">Zend_Acl</span> provides a tree structure to which multiple resources
            can be added. Since resources are stored in such a tree structure, they can be
            organized from the general (toward the tree root) to the specific (toward the tree
            leaves). Queries on a specific resource will automatically search the resource&#039;s
            hierarchy for rules assigned to ancestor resources, allowing for simple inheritance of
            rules. For example, if a default rule is to be applied to each building in a city, one
            would simply assign the rule to the city, instead of assigning the same rule to each
            building. Some buildings may require exceptions to such a rule, however, and this can
            be achieved in <span class="classname">Zend_Acl</span> by assigning such exception rules to
            each building that requires such an exception. A resource may inherit from only one
            parent resource, though this parent resource can have its own parent resource, etc.
        </p>

        <p class="para">
            <span class="classname">Zend_Acl</span> also supports privileges on resources (e.g., &quot;create&quot;,
            &quot;read&quot;, &quot;update&quot;, &quot;delete&quot;), so the developer can assign rules that affect all
            privileges or specific privileges on one or more resources.
        </p>
    </div>

    <div class="section" id="zend.acl.introduction.roles"><div class="info"><h1 class="title">Roles</h1></div>
        

        <p class="para">
            As with resources, creating a role is also very simple. All roles must implement
            <span class="classname">Zend_Acl_Role_Interface</span>. This interface consists of a single
            method,  <span class="methodname">getRoleId()</span>, Additionally,
            <span class="classname">Zend_Acl_Role</span> is provided by <span class="classname">Zend_Acl</span> as
            a basic role implementation for developers to extend as needed.
        </p>

        <p class="para">
            In <span class="classname">Zend_Acl</span>, a role may inherit from one or more roles. This is
            to support inheritance of rules among roles. For example, a user role, such as &quot;sally&quot;,
            may belong to one or more parent roles, such as &quot;editor&quot; and &quot;administrator&quot;. The
            developer can assign rules to &quot;editor&quot; and &quot;administrator&quot; separately, and &quot;sally&quot;
            would inherit such rules from both, without having to assign rules directly to &quot;sally&quot;.
        </p>

        <p class="para">
            Though the ability to inherit from multiple roles is very useful, multiple inheritance
            also introduces some degree of complexity. The following example illustrates the
            ambiguity condition and how <span class="classname">Zend_Acl</span> solves it.
        </p>

        <div class="example" id="zend.acl.introduction.roles.example.multiple_inheritance"><div class="info"><p><b>Example #1 Multiple Inheritance among Roles</b></p></div>
            

            <div class="example-contents"><p>
                The following code defines three base roles - &quot;guest&quot;,
                &quot;member&quot;, and &quot;admin&quot; - from which other roles may
                inherit. Then, a role identified by &quot;someUser&quot; is established and
                inherits from the three other roles. The order in which these roles appear in the
                <var class="varname">$parents</var> array is important. When necessary,
                <span class="classname">Zend_Acl</span> searches for access rules defined not only for the
                queried role (herein, &quot;someUser&quot;), but also upon the roles from which
                the queried role inherits (herein, &quot;guest&quot;, &quot;member&quot;, and
                &quot;admin&quot;):
            </p></div>

            <pre class="programlisting brush: php">
$acl = new Zend_Acl();

$acl-&gt;addRole(new Zend_Acl_Role(&#039;guest&#039;))
    -&gt;addRole(new Zend_Acl_Role(&#039;member&#039;))
    -&gt;addRole(new Zend_Acl_Role(&#039;admin&#039;));

$parents = array(&#039;guest&#039;, &#039;member&#039;, &#039;admin&#039;);
$acl-&gt;addRole(new Zend_Acl_Role(&#039;someUser&#039;), $parents);

$acl-&gt;add(new Zend_Acl_Resource(&#039;someResource&#039;));

$acl-&gt;deny(&#039;guest&#039;, &#039;someResource&#039;);
$acl-&gt;allow(&#039;member&#039;, &#039;someResource&#039;);

echo $acl-&gt;isAllowed(&#039;someUser&#039;, &#039;someResource&#039;) ? &#039;allowed&#039; : &#039;denied&#039;;
</pre>


            <div class="example-contents"><p>
                Since there is no rule specifically defined for the &quot;someUser&quot; role and
                &quot;someResource&quot;, <span class="classname">Zend_Acl</span> must search for rules that may be
                defined for roles that &quot;someUser&quot; inherits. First, the &quot;admin&quot; role is visited, and
                there is no access rule defined for it. Next, the &quot;member&quot; role is visited, and
                <span class="classname">Zend_Acl</span> finds that there is a rule specifying that &quot;member&quot;
                is allowed access to &quot;someResource&quot;.
            </p></div>

            <div class="example-contents"><p>
                If <span class="classname">Zend_Acl</span> were to continue examining the rules defined for
                other parent roles, however, it would find that &quot;guest&quot; is denied access to
                &quot;someResource&quot;. This fact introduces an ambiguity because now
                &quot;someUser&quot; is both denied and allowed access to &quot;someResource&quot;, by reason of having
                inherited conflicting rules from different parent roles.
            </p></div>

            <div class="example-contents"><p>
                <span class="classname">Zend_Acl</span> resolves this ambiguity by completing a query when
                it finds the first rule that is directly applicable to the query. In this case,
                since the &quot;member&quot; role is examined before the &quot;guest&quot; role, the example code would
                print &quot;allowed&quot;.
            </p></div>
        </div>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                When specifying multiple parents for a role, keep in mind that the last parent
                listed is the first one searched for rules applicable to an authorization query.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.acl.introduction.creating"><div class="info"><h1 class="title">Creating the Access Control List</h1></div>
        

        <p class="para">
            An Access Control List (<acronym class="acronym">ACL</acronym>) can represent any set of physical or
            virtual objects that you wish. For the purposes of demonstration, however, we will
            create a basic Content Management System (<acronym class="acronym">CMS</acronym>)
            <acronym class="acronym">ACL</acronym> that maintains several tiers of groups over a wide variety of
            areas. To create a new <acronym class="acronym">ACL</acronym> object, we instantiate the
            <acronym class="acronym">ACL</acronym> with no parameters:
        </p>

        <pre class="programlisting brush: php">
$acl = new Zend_Acl();
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                Until a developer specifies an &quot;allow&quot; rule, <span class="classname">Zend_Acl</span> denies
                access to every privilege upon every resource by every role.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.acl.introduction.role_registry"><div class="info"><h1 class="title">Registering Roles</h1></div>
        

        <p class="para">
            <acronym class="acronym">CMS</acronym>&#039;s will nearly always require a hierarchy of permissions to
            determine the authoring capabilities of its users. There may be a &#039;Guest&#039; group to
            allow limited access for demonstrations, a &#039;Staff&#039; group for the majority of
            <acronym class="acronym">CMS</acronym> users who perform most of the day-to-day operations, an &#039;Editor&#039;
            group for those responsible for publishing, reviewing, archiving and deleting content,
            and finally an &#039;Administrator&#039; group whose tasks may include all of those of the other
            groups as well as maintenance of sensitive information, user management, back-end
            configuration data, backup and export. This set of permissions can be represented in a
            role registry, allowing each group to inherit privileges from &#039;parent&#039; groups, as well
            as providing distinct privileges for their unique group only. The permissions may be
            expressed as follows:
        </p>

        <table id="zend.acl.introduction.role_registry.table.example_cms_access_controls" class="doctable table"><div class="info"><caption><b>Access Controls for an Example CMS</b></caption></div>
            
            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Name</th>
                        <th>Unique Permissions</th>
                        <th>Inherit Permissions From</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left">Guest</td>
                        <td align="left">View</td>
                        <td align="left">N/A</td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Staff</td>
                        <td align="left">Edit, Submit, Revise</td>
                        <td align="left">Guest</td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Editor</td>
                        <td align="left">Publish, Archive, Delete</td>
                        <td align="left">Staff</td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Administrator</td>
                        <td align="left">(Granted all access)</td>
                        <td align="left">N/A</td>
                    </tr>

                </tbody>
            
        </table>


        <p class="para">
            For this example, <span class="classname">Zend_Acl_Role</span> is used, but any object that
            implements <span class="classname">Zend_Acl_Role_Interface</span> is acceptable. These groups
            can be added to the role registry as follows:
        </p>

        <pre class="programlisting brush: php">
$acl = new Zend_Acl();

// Add groups to the Role registry using Zend_Acl_Role
// Guest does not inherit access controls
$roleGuest = new Zend_Acl_Role(&#039;guest&#039;);
$acl-&gt;addRole($roleGuest);

// Staff inherits from guest
$acl-&gt;addRole(new Zend_Acl_Role(&#039;staff&#039;), $roleGuest);

/*
Alternatively, the above could be written:
$acl-&gt;addRole(new Zend_Acl_Role(&#039;staff&#039;), &#039;guest&#039;);
*/

// Editor inherits from staff
$acl-&gt;addRole(new Zend_Acl_Role(&#039;editor&#039;), &#039;staff&#039;);

// Administrator does not inherit access controls
$acl-&gt;addRole(new Zend_Acl_Role(&#039;administrator&#039;));
</pre>

    </div>

    <div class="section" id="zend.acl.introduction.defining"><div class="info"><h1 class="title">Defining Access Controls</h1></div>
        

        <p class="para">
            Now that the <acronym class="acronym">ACL</acronym> contains the relevant roles, rules can be
            established that define how resources may be accessed by roles. You may have noticed
            that we have not defined any particular resources for this example, which is simplified
            to illustrate that the rules apply to all resources. <span class="classname">Zend_Acl</span>
            provides an implementation whereby rules need only be assigned from general to
            specific, minimizing the number of rules needed, because resources and roles inherit
            rules that are defined upon their ancestors.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                In general, <span class="classname">Zend_Acl</span> obeys a given rule if and only if a
                more specific rule does not apply.
            </p>
        </p></blockquote>

        <p class="para">
            Consequently, we can define a reasonably complex set of rules with a minimum amount of
            code. To apply the base permissions as defined above:
        </p>

        <pre class="programlisting brush: php">
$acl = new Zend_Acl();

$roleGuest = new Zend_Acl_Role(&#039;guest&#039;);
$acl-&gt;addRole($roleGuest);
$acl-&gt;addRole(new Zend_Acl_Role(&#039;staff&#039;), $roleGuest);
$acl-&gt;addRole(new Zend_Acl_Role(&#039;editor&#039;), &#039;staff&#039;);
$acl-&gt;addRole(new Zend_Acl_Role(&#039;administrator&#039;));

// Guest may only view content
$acl-&gt;allow($roleGuest, null, &#039;view&#039;);

/*
Alternatively, the above could be written:
$acl-&gt;allow(&#039;guest&#039;, null, &#039;view&#039;);
//*/

// Staff inherits view privilege from guest, but also needs additional
// privileges
$acl-&gt;allow(&#039;staff&#039;, null, array(&#039;edit&#039;, &#039;submit&#039;, &#039;revise&#039;));

// Editor inherits view, edit, submit, and revise privileges from
// staff, but also needs additional privileges
$acl-&gt;allow(&#039;editor&#039;, null, array(&#039;publish&#039;, &#039;archive&#039;, &#039;delete&#039;));

// Administrator inherits nothing, but is allowed all privileges
$acl-&gt;allow(&#039;administrator&#039;);
</pre>


        <p class="para">
            The <b><tt>NULL</tt></b> values in the above  <span class="methodname">allow()</span> calls
            are used to indicate that the allow rules apply to all resources.
        </p>
    </div>

    <div class="section" id="zend.acl.introduction.querying"><div class="info"><h1 class="title">Querying an ACL</h1></div>
        

        <p class="para">
            We now have a flexible <acronym class="acronym">ACL</acronym> that can be used to determine whether
            requesters have permission to perform functions throughout the web application.
            Performing queries is quite simple using the  <span class="methodname">isAllowed()</span>
            method:
        </p>

        <pre class="programlisting brush: php">
echo $acl-&gt;isAllowed(&#039;guest&#039;, null, &#039;view&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed

echo $acl-&gt;isAllowed(&#039;staff&#039;, null, &#039;publish&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// denied

echo $acl-&gt;isAllowed(&#039;staff&#039;, null, &#039;revise&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed

echo $acl-&gt;isAllowed(&#039;editor&#039;, null, &#039;view&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed because of inheritance from guest

echo $acl-&gt;isAllowed(&#039;editor&#039;, null, &#039;update&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// denied because no allow rule for &#039;update&#039;

echo $acl-&gt;isAllowed(&#039;administrator&#039;, null, &#039;view&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed because administrator is allowed all privileges

echo $acl-&gt;isAllowed(&#039;administrator&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed because administrator is allowed all privileges

echo $acl-&gt;isAllowed(&#039;administrator&#039;, null, &#039;update&#039;) ?
     &quot;allowed&quot; : &quot;denied&quot;;
// allowed because administrator is allowed all privileges
</pre>

    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.acl.html">Zend_Acl</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.acl.html">Zend_Acl</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.acl.refining.html">Refining Access Controls</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.acl.html">Zend_Acl</a></li>
  <li class="active"><a href="zend.acl.introduction.html">Introduction</a></li>
  <li><a href="zend.acl.refining.html">Refining Access Controls</a></li>
  <li><a href="zend.acl.advanced.html">Advanced Usage</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>